home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / program / tmtpl37d.zip / MANUAL.DOS < prev    next >
Text File  |  1996-10-17  |  38KB  |  1,166 lines
  1.                    Pascal Lite Compiler for MS DOS
  2.                          [ Version 0.37 ]
  3.  
  4.                     TMT Development Corporation
  5.  
  6.  
  7.       [[[ SEARCH THIS FILE FOR 0.nn FOR THE NEW VERSION INFORMATION ]]]
  8.  
  9.  
  10. Introduction
  11. ------------
  12.  
  13. The TMT Pascal Lite compiler is a fast compiler for the Pascal language.
  14. The compiler emits 32-bit code and supports many language extensions
  15. from Borland Pascal (BP), as well as more powerful extensions.
  16.  
  17. The compiler requires at least 2Mb of free extended memory (XMS) and
  18. a floating point co-processor.
  19.  
  20.  
  21. This manual consists of the following parts:
  22.  
  23.     - introduction
  24.     - free version limitations
  25.     - compiler installation and running
  26.     - configuration file
  27.     - memory organization
  28.     - calling convention
  29.     - implemented language description:
  30.          - restriction
  31.          - extensions
  32.          - incompatibilities
  33.     - units description:
  34.          - DOS
  35.          - CRT
  36.          - USE32
  37.          - ERRCODES
  38.          - DEBUG
  39.          - STRINGS
  40.     - version 0.33 changes
  41.     - possible problems during usage
  42.     - run_time error codes
  43.  
  44.  
  45. Free Version Limitations---Getting an unrestricted Version
  46. ----------------------------------------------------------
  47.  
  48.    The free version of the PLT compiler limits the size of the executible
  49.    program code+data+heap to approximately 1.5mb. If this restriction
  50.    prevents you from implementing your application, you should obtain
  51.    a licensed copy of the compiler.
  52.  
  53.    The special pre-release price of an unrestricted version of the compiler
  54.    is only US$50. The distribution is electronic; if you desire your software
  55.    to be shipped by regular mail, please contact sales@tmt.com for details.
  56.  
  57.    Unrestricted license will get you the current version of the compiler
  58.    plus all updates until a commercial version is released.
  59.  
  60.    To order your copy of PLT/Lite, send an email to sales@tmt.com
  61.    with the credit card information (VISA, MC, AMEX, DISCOVER). Alternatively,
  62.    call 1-718-268-3756 (10-5 EST) or send check or postal order to
  63.  
  64.    TMT Development Corp.
  65.    19 POPLAR AVE,
  66.    Stony Brook, NY 11790-1751
  67.  
  68.    Foreign orders: if you are paying by check, please make sure
  69.    that your check is in US dollars and drawn on a US bank.
  70.  
  71.    All postal orders: please make sure that your order specifies a contact
  72.    email account.
  73.  
  74.    PO's: we will accept PO's from qualified institutions in US and Canada.
  75.    Please verify that your PO will be accepted before issuing it.
  76.  
  77.  
  78. Compiler installation and running
  79. ---------------------------------
  80.  
  81.    The Pascal Lite distribution is contained in the tmtpldos.zip archive.
  82.    Please, read the license.doc file before the installation.
  83.  
  84.    Follow these instructions to run the installation process.
  85.  
  86.       - create the \TMTPL directory on one of the drives (we will call
  87.         it the x: drive) using the command:
  88.             x> md TMTPL
  89.  
  90.       - copy the tmtpl37d.zip file into the TMTPL directory:
  91.  
  92.             x> copy  tmtpl37d.zip x:\TMTPL
  93.             x> x:
  94.             x> cd \TMTPL
  95.  
  96.       - run the PKUNZIP program to decompress the TMTPL37d.ZIP
  97.  
  98.             x:\TMTPL> pkunzip -d tmtpl37d
  99.  
  100.         (the switch "-d" unpacks with subdirectories)
  101.  
  102.       - modify the PATH statement in the autoexec.bat, to include the
  103.                 x:\TMTPL\BIN
  104.          subdirectory, if you so desire.
  105.  
  106.       - goto to \TMTPL\EXAMPLES\DOS\HELLO
  107.         compile the simple test program, "HELLO.PAS", and run it:
  108.  
  109.            x:\TMTPL> plt hello
  110.            x:\TMTPL> hello
  111.  
  112.       - read the entire manual.doc file before using the compiler for
  113.         any "real" application development.
  114.  
  115.  
  116. Contents of the distribution
  117. ----------------------------
  118.  
  119.    documentation:
  120.  
  121.       manual.doc         - description of the PLT compiler
  122.       license.doc        - license agreement
  123.       readme             - this file
  124.  
  125.    executable:
  126.  
  127.      subdirectory BIN contains following files:
  128.  
  129.        plt.cfg            - compiler configuration file
  130.        dos32.exe          - the DOS32 protected mode extender
  131.        dos4gw.exe         - the DOS/4GW protected mode extender (used by
  132.                            compiler)
  133.        plt.exe            - the PLT compiler under the DOS/4GW extender
  134.        pltpmw.exe         - the PLT compiler under the PMODE extender
  135.  
  136.    standard library object modules:
  137.  
  138.      subdirectory UNITS\ contains unit obj modules files with .FPD
  139.      extensions
  140.  
  141.       arg                - commmand line parsing unit
  142.       crt                - crt unit
  143.       debug              - post-mortem dump unit and other debugging
  144.                            functions
  145.       dos.fpd            - dos unit
  146.       doscall            - low-level DOS interface
  147.       errcodes           - run-time error codes
  148.       strings            - strings unit
  149.       system             - system unit
  150.  
  151.       also in this directory contains files:
  152.           DOS32.EXE   - DOS32 extender
  153.           STUB32.EXE  - stub for DOS32 extender
  154.           PASSTUB.EXE - PMODE-based extender
  155.  
  156.    example:
  157.  
  158.      subdirectory EXAMPLE\ contains following examples for MS DOS:
  159.  
  160.        HELLO\ - example "Hello, World" program
  161.        FLAME\ - example of direct works with I/O ports and physical
  162.                 memory
  163.        VESADEMO\ - example of import and usage VESA.OBJ file from
  164.                   DOS32 libraries.
  165. +++0.33
  166.        LIN_EQ\ - example of multidimensional open arrays usage
  167. ---0.33
  168.  
  169.    supplemential files:
  170.  
  171.       DOS32\              - subdirectory that contains the DOS32
  172.                            distribution to be used by the application.
  173.  
  174.    Running the compiler:
  175.    --------------------
  176.  
  177. The compiler is invoked with the "plt" command:
  178.  
  179.   plt [switches] <main file>
  180.  
  181. where the following switches can be used:
  182.  
  183.     -m   - make modified units (default option)
  184.     -b   - build the whole program
  185.     -c   - single compilation (without linkage)
  186.  
  187. After that the suite of object files with .FPD extensions will be
  188. established in the directory with the sources, and the executable file
  189. will be created in the current directory (if the switch -c is not set).
  190.  
  191. Instead of the "plt.exe" file there is another version of the compiler
  192. which uses the freeware extender PMODE. This is a "pltpmw.exe" file.
  193. This compiler demands less memory for the compilation and works faster
  194. then "plt.exe". Try to use it. If problems arise, use "plt.exe".
  195.  
  196.  
  197. Out of memory message
  198.  
  199. If you receive message "not enough memory for compilation", you have to
  200. either:
  201.  
  202.    - increase  a amount of free extended memory (for example, decrease
  203.      the "cash" of your hard disk), or
  204.    - decrease the value of the EXEMAK and OBJMAX parameters in the configuration
  205.      file, or
  206.    - switch on the virtual memory of DOS/4GW: To do this, include a line
  207.      "SET DOS4GW=1" into the your AUTOEXEC.BAT and use the compiler version
  208.      under the DOS/4GW extender.
  209.  
  210.  
  211. Configuration file
  212. ------------------
  213.  
  214. Before a compilation the compiler reads the settings from the special file -
  215. plt.cfg. It searches for one at the beginning of the current directory and
  216. then, if it doesn't find one, in the starting directory.
  217.  
  218. The configuration file "plt.cfg" contains the compilation parameters:
  219. one command per line. Empty line are possible. Comment line are started with
  220. the ';' symbol.
  221.  
  222. The following parameters can be used in the plt.cfg:
  223.  
  224.     toggle settings:
  225.  
  226.        w+       - turn on the puting of warning messages
  227.        r+       - turn on the range checking
  228.        q+       - turn on the overflow checking
  229.        i+       - turn on then automatic input/output result checking
  230.        t+       - typed pointers
  231.        x+       - extended syntax
  232.        v+       - strict var checking
  233.        optreg+  - turn on the register optimization
  234.        optfrm+  - turn on the stack frame optimization
  235.        opt+     - turn on all optimization (optreg+ & optfrm+)
  236.  
  237.     Default settings: w+, r+, q+, i+, t-, v+, x+, opt+.
  238.  
  239.     file path search specification:
  240.  
  241.        srcpath    <search_path> - specifies path for the source file search
  242.        objpath    <search_path> - specifies path for the object file (.FPD)
  243.                                   and STUBs search
  244.        objimppath <search_path> - specifies path for the OBJ import file
  245.                                   search by use of a $L directive
  246.  
  247.  
  248.        pseudo-devices SYS: and SRC: can be used in the path line:
  249.  
  250.          SYS: means the PLT compiler directory,
  251.          SRC: means the application program directory.
  252.  
  253.        defaults:  srcpath     src:;sys:
  254.                   objpath     src:;sys:
  255.                   objimppath  src:;sys:
  256.  
  257.  
  258.     buffer size specification:
  259.  
  260.        objmax <size>    - specifiies the size of the buffer for object
  261.                           modules (fpd-files). This parameter must be
  262.                           about one and a half times the size of the
  263.                           largest fpd-file from the project.
  264.  
  265.        exemax <size>    - specifies the maximum size of the executable
  266.                           module.
  267.  
  268.  
  269.        defaults:   objmax 333000
  270.                    exemax 256000
  271.  
  272.        These values are enough for ordinary work.  But if you receive
  273.        a message about overflowing of these buffers, you'll have to
  274.        increase them.  If you receive the message about unsufficient memory
  275.        for the compilation, you can try to decrease them.
  276.  
  277.     stack size specification:
  278.  
  279.        stack <stack_size> - specifies size of the application stack
  280.        default: 32000
  281.  
  282.     start up block (stub) name specification:
  283.  
  284.        stub  <stub_name>  - specifies the STUB name for the linker.
  285.                             default: DOS32.EXE
  286. +++0.30
  287.                             use the OBJPATH option to specify the seacrh path
  288.                             for the stub files
  289. ---0.30
  290.  
  291.  
  292.  
  293.     Symbol definition:
  294.  
  295.        def <symbol name>
  296.  
  297. +++0.30
  298.            The following symbols are predefined:
  299.                 __TMT__ :    always
  300.                 __DOS__ :    for DOS target
  301.             *   __OS2__ :    for all OS/2 targets
  302.             *   __DLL__ :    for .DLL targets
  303.             *   __PM__  :    for OS/2 Presentation manager targets
  304.             *   __FS__  :    for OS/2 Full screen targets
  305.             *           --   OS/2-hosted compiler only
  306. ---0.30
  307.  
  308.  
  309.     error message format specification:
  310.  
  311.  
  312.  
  313.        errmw+ - specifies the MetaWare Pascal format of the error message:
  314.  
  315.                    E "HELLO.PAS" L4/C16: type mismatch
  316.  
  317.  
  318.        errmw- - specifies BP-like format of the error message:
  319.  
  320.                    textcolor (lightred+'a');
  321.                               
  322.                    Error: HELLO.PAS (line 4, col 16): type mismatch
  323.  
  324.        This parameter allows use of the MultiEdit program as a shell
  325.        when the errmw+ parameter is set.
  326.  
  327.        The default is:  errmw-
  328.  
  329.      Output of the Dos32 logo specification:
  330.  
  331.        logo+  -  enables output of the Dos32 logo during the running of
  332.                  the emitted program.
  333.        logo-  -  disables output of the Dos32 logo during the running of
  334.                  the emitted program.
  335.  
  336.        The default is: logo+
  337.  
  338. Memory organization
  339. -------------------
  340.  
  341. The PLT compiler uses the Dos32 extender for a protected-mode program.
  342. The full distributive of Dos32 is in the DOS32 subdirectory.
  343. This distributive contains all information about program execution
  344. under the 32-bit mode.  Here some important issues are presented.
  345.  
  346. The segment registers are not used in the protected mode.  Instead all
  347. address space is separated on 4Kb pages starting from the zero address.
  348. Every page has a physical equivalent in the special table (the physical
  349. address might not be equal to the logical address).  In such a case the
  350. logical address 0 corresponds to the beginning of the program code.
  351. Therefore if you try to access the physical address (video memory and so
  352. on), you will not succeed.
  353.  
  354. Nevertheless, access to the physical addresses is possible, because
  355. the Dos32 extender reflects physical addresses into another set of special
  356. address pages.  To find the logical address from physical, you have to add
  357. the value of the special _zero varible from the SYSTEM unit to the physical
  358. address.
  359.  
  360. For example:
  361.  
  362.         procedure clr_video (filler: char);
  363.            var i: integer;
  364.         begin
  365.            for i := 0 to 80*25-1 do
  366.                mem [_zero+$B8000+i*2] := filler;
  367.         end;
  368.  
  369. This procedure fills the video memory of the VGA adapter with the
  370. filler symbol.
  371.  
  372. Note that the linear address $B8000 is used as the physical address - not
  373. the segment address $B800.
  374.  
  375. Some another special variables are described in the SYSTEM unit.
  376. The _psp variable contains the logical 32-bit address of the PSP of the
  377. program, and the _environ variable contains the environment address.
  378.  
  379. Although you can access the interrupt vectors by using this method,
  380. we do not suggest doing this.
  381.  
  382.  
  383.     Also keep in mind that MS-DOS interrupt handlers use memory
  384.     addresses in the 1st mb of physical memory while your program
  385.     and its data are loaded beyond the 1st mb. DOS32 intercepts
  386.     and correctly handles some, but not all, calls to MS-DOS.
  387.     Thus, if you are using Intr() or MsDos() calls, or call MS-DOS from
  388.     the assembler, you will need to modify the code.
  389.  
  390.     Additional details about this and related subjects can be found in
  391.     DOS32.DOC and API.DOC in subdirectory DOS32.
  392.  
  393.              Calling conventions
  394.              -------------------
  395.  
  396. Calling conventions match those in Borland Pascal with the following
  397. differences:
  398.  
  399.      all parameters use 4 bytes on the stack, or a multiple of 4 (BP:2)
  400.  
  401.      all procedures must preserve the contents of registers ebx, ecx, edx,
  402.      ds, and es!
  403.  
  404.      the direction bit should be cleared after the exit from a procedure,
  405.      if it has been modified by it.
  406.  
  407.  
  408.                 Language syntax of TMT Pascal/Fast:
  409.                 -----------------------------------
  410.  
  411. While the Language syntax of TMT Pascal/Fast is in general compatible with
  412. BP 7.0, there are some differences. Below is the list, divided into three
  413. groups: limitations, extensions, and incompatibilities.
  414.  
  415.  
  416.    1. Limitations:
  417.  
  418. Not implemented are MARK and RELEASE.
  419.  
  420. The INLINE() operator in implemented in a partial form:
  421.     INLINE (byte/byte/...);
  422. (No references to variables/constants are allowed).
  423.  
  424. Import of object modules does not support all 32bit object formats.
  425. We recommend using TASM which is fully supported, excepting
  426. usage of SEG addresses.
  427.  
  428.  
  429.    2. Extensions:
  430.  
  431. ADA-style comments are supported:  -- comment
  432. For example:
  433.  
  434.       space := ' ';  -- initialize filler char
  435.  
  436.  
  437.  
  438. Almost everywhere where Pascal's syntax allows a type identifier, we
  439. also allow a type descriptor. The compiler will produce a warning if you
  440. use this feature.
  441.  
  442. !!! Keep in mind that the rules of type equivalence stay in force.
  443.  
  444. Procedural values contain the address of the local environment (frame).
  445. Thus, any local procedures can be used in procedural values. Procedural
  446. declaration in the style
  447.  
  448.     procedure p (function f (a:real):real); ...
  449.  
  450. are also realized.
  451.  
  452.  
  453. The procedural value from a method of object can be obtained by
  454. selecting this method from some object value (not from a type). The
  455. parameters of this procedural value must match the parameters of the
  456. method.  The invocation of such a procedural value is an invocation of the
  457. corresponding method of the object.  The reference to the object is
  458. transferred through the base of the procedural value.
  459.  
  460. You can use only global procedural values to initialize a type constant.
  461.  
  462. !!! Procedural values may be used only while the environment where
  463. they were formed is still in existence.  Thus, for local procedures
  464. -- until the exit from the block, in which they are described; for
  465. methods -- while the underlying object still exists.
  466.  
  467. see also "incompatibilities."
  468.  
  469. With TMT Pascal you can use any statement as a procedure body,
  470. except for the assignment and the procedure calls.
  471.  
  472. The RESULT variable in the body of such functions denotes the variable
  473. that contains the return value.  The RESULT is of the function return type
  474. and may be used as a variable without any restrictions.
  475.  
  476. With TMT Pascal you can enter the procedure body directly as a procedure
  477. parameter.  The procedure or function header (if not specified) takes the
  478. procedural parameter type.  If the procedure header is specified, the
  479. procedure name is omitted.  Example:
  480.  
  481. function integral (function f (a:real):real; low, high, step: real): real;
  482. begin ... end;
  483.  
  484.     ...
  485.     writeln (integral (
  486.          function (x:real):real; begin result := sqrt (x) end,
  487.     0, 10, 0.1));
  488.  
  489.     writeln (integral (begin result := sqrt (a) end, 0, 10, 0.1));
  490.  
  491.     writeln (integral (
  492.          function;        -- function keyword needed
  493.              var x: real; -- for local declaration
  494.          begin x := sqrt (a); result := x end,
  495.     0, 10, 0.1));
  496.  
  497.     writeln (integral (
  498.          declare;         -- other way
  499.              var x: real; -- for local variable declaration
  500.          begin x := sqrt (a); result := x end,
  501.     0, 10, 0.1));
  502.  
  503. TMT Pascal allows exit from a local procedure to the one that contains it.
  504. This feature is listed in the Pascal's ANSI standard but not realized in
  505. BP. Together with procedural values, this is very useful for error handling:
  506.  
  507. Program test;
  508.     Var on_eof: procedure;
  509.     Function read_char: char;
  510.         Var c: char;
  511.     Begin
  512.         If Eof (Input) Then on_eof;
  513.         read (c);
  514.         read_char := c;
  515.     End;
  516.  
  517.     Procedure p;
  518.         Label eof_reached;
  519.         Procedure go_eof; Begin goto eof_reached; End;
  520.     Begin
  521.         on_eof := go_eof;
  522.         While True Do Write (read_char);
  523.     Eof_reached:
  524.         Writeln ('*** EOF ***');
  525.         on_eof := NIL;
  526.     End;
  527.  
  528. Begin
  529.     p;
  530. End.
  531.  
  532. Restriction: BREAK and CONTINUE operators cannot be used for exit
  533. from a procedure. Use GOTO instead.
  534.  
  535. Example:
  536.  
  537.         for i := 1 to 10 do
  538.             writeln (integral (  -- function integral from previous example
  539.                 if a < 0 then break else result := sqrt (a), -- incorrect
  540.             i, i + 1, 0.01));
  541.  
  542.         declare
  543.             label L;
  544.         begin
  545.             for i := 1 to 10 do
  546.                 writeln (integral (
  547.                     if a < 0 then goto L else result := sqrt (a), -- correct
  548.                 i, i + 1, 0.01));
  549.         L: end;
  550.  
  551. Functions may return any values of any type, including structures and arrays.
  552.  
  553.  
  554. The new operator DECLARE
  555.  
  556.    DECLARE
  557.        <declaration part>
  558.    BEGIN
  559.        <statement list>
  560.    END
  561.  
  562.  
  563. allows one to describe local variables and procedures anywhere in the
  564. program.  Use of "DECLARE" leads to more readable programs and conserves
  565. the stack space.
  566.  
  567. Functions length, chr, ord may be used as variables. For example:
  568.  
  569.          chr (i) := ' ';   is equivalent to   i := ord (' ');
  570.          ord (c) := 255;   is equivalent to   c := chr (255);
  571.          length (s) := 10; is equivalent to   s [0] := chr (10);
  572.  
  573.  
  574. The main program may contain "interface" and "implementation".
  575. This allows access to the variables of the main program from other
  576. modules:
  577.  
  578.     Program test;
  579.     Interface
  580.        Var global: Integer;
  581.     Implementation
  582.        Uses Unit_test;
  583.     Begin
  584.        Unit_test.write;
  585.     End.
  586.  
  587.     Unit Unit_test;
  588.     Interface
  589.         Procedure Write_global;
  590.     Implementation
  591.         Uses test;
  592.         Procedure Write_global;
  593.         Begin
  594.             Write (test.global);
  595.         End;
  596.     End.
  597.  
  598.  
  599. !!! Here the name of the file that contains the text of the main program
  600. must be identical with the name that follows the keyword "program".
  601.  
  602. New type: DWORD - an unsigned 32-bit integer (same as unsigned long in C).
  603. It can be useful in many cases, but keep in mind that during arithmetic
  604. operations between DWORD's and LONGINT's both arguments are casted to
  605. LONGINT's. This may cause an error.
  606.  
  607. ABSOLUTE may refer to fields of records and objects.  Also, the
  608. address of a global record/object field can be used within the initialization
  609. of typed constants.  Furthermore one can use recursive initialization:
  610.  
  611. type rec = record
  612.                next: ^rec;
  613.                buffer: array [1..10] of char;
  614.                buf_adr: pointer;
  615.            end;
  616.  
  617. const cyclic: rec = (next: @cyclic; buf_adr: @cyclic.buffer);
  618.  
  619. In initialization of structures and objects the fields may go in
  620. an arbitrary order. If a field is not listed, it is zeroed up.
  621.  
  622. The syntax of the STR operator has been extended:
  623.  
  624.     STR (value[:width[:precision]], ..., dest);
  625.  
  626. Here STR (name:2, ':', ext:3, dst); is equivalent to
  627.  
  628.         STR (name:2, temp1);
  629.         STR (':',    temp2);
  630.         STR (ext:3,  temp3);
  631.         dst := temp1 + temp2 + temp3;
  632.  
  633. Negative field widths in WRITE, WRITELN, and STR left align the value within
  634. its field.
  635.  
  636. !!! The Strings unit contains additional functions which may be more
  637.     convenient than the STR operator.
  638.  
  639. +++0.30
  640.  
  641.      Multidimensional open arrays:
  642.  
  643. You can now use in procedure parameters and functions descriptions
  644. "array (<dim>) of <type>", where <dim> is a positive integer constant, defining
  645. the number of dimensions, ánd <type> is the type of the array elements.
  646. To determine the upper bounds of the array, use the "high (array)" function.
  647. It returns a vector of longints ("array [0..<dim>-1] of longint") containing
  648. the upper bounds. The lower bounds are always set to 0. The vector of the lower
  649. bounds can be obtained with a similar function "low".
  650.  
  651. Example:
  652.  
  653.  
  654. procedure print_vector (v: array (1) of double);
  655. var i: integer;
  656. begin
  657.     for i := 0 to high (v) [0] do write (v [i]:10:6, ' ');
  658.     writeln;
  659. end;
  660.  
  661. procedure print_matrix (m: array (2) of double);
  662. var i: integer;
  663. begin
  664.     for i := 0 to high (m) [0] do print_vector (m [i]);
  665.     writeln;
  666. end;
  667.  
  668. const a: array [1..3, 1..3] of double = ((1,0,2),(2,1,0),(1,2,1));
  669.  
  670. begin
  671.     print_matrix (a);
  672. end.
  673.  
  674. You can find an example program for solving a system of linear equations in
  675. the directory "EXAMPLES\LIN_EQ".
  676.  
  677. ---0.30
  678.  
  679.  
  680.     3. Incompatibilities:
  681.  
  682. Procedural values is 8-byte long and has the following format:
  683.  
  684. 0   +-----------------------+
  685.     | The entry point       |
  686. 4   +-----------------------+
  687.     | The local environment |
  688. 8   +-----------------------+
  689.  
  690. However, a pointer to a procedure is only 4-byte long and contain only the
  691. address of the entry point. The @ operator verifies that the procedure is
  692. global. Otherwise a range error is generated.
  693.  
  694. Furthermore, the stack frame structure and parameter passing conventions
  695. differ from those in BP.
  696.  
  697. Thus the approach used in TVision and CLassLib for writing iterators
  698. cannot be used. However, we offer this correct and reliable (and more
  699. standard) way:
  700.  
  701.      Type list = object
  702.                      next: ^list;
  703.                      procedure for_all (procedure body (var v));
  704.                  end;
  705.  
  706.      Procedure list.for_all;
  707.          Var p: ^list;
  708.      Begin
  709.          p := @self;
  710.          repeat
  711.              body (p);
  712.              p := p^.next;
  713.          end;
  714.      End;
  715.  
  716.      ...
  717.  
  718.      Type int_list = object (list)
  719.                          value: integer;
  720.                          function first_positive: ^int_list;
  721.                      end;
  722.  
  723.      Function int_list.first_positive;
  724.          Label OK;
  725.          Var res: ^int_list;
  726.          Procedure do_item (var v);
  727.          Begin
  728.              If int_list (v).value > 0 Then
  729.              Begin
  730.                  res := @v;
  731.                  GoTo OK;
  732.              End
  733.          End;
  734.      Begin
  735.          res := nil;
  736.          for_all (do_item);
  737.      OK:
  738.          first_positive := res;
  739.      End;
  740.  
  741.      ...
  742.  
  743.  
  744.  
  745. Since in the flat model there are no segments, SEG() always returns 0,
  746. while PTR() ignores its first parameter.
  747.  
  748. !!! Be careful with these functions: in practice, any use of PTR() or SEG()
  749.     in your program may require a program modification.
  750.  
  751. Pseudo-array Mem and MemW are used as follows:
  752.  
  753.     i := MemW [<linear address>]
  754.  
  755. Note that the segment is not given. Furthermore, the pseudo-arrays
  756. MemD and PortD of type DWORD are available.
  757.  
  758. See "Memory organization" for more details.
  759.  
  760.  
  761.            Built-in assembler
  762.            ------------------
  763.  
  764. The built-in assembler of TMT Pascal Lite is 32-bit.  It is compatible
  765. with the BP's built-in assembler with the following differences:
  766.  
  767. Since the program created by the Pascal Lite is executed in the flat
  768. model, the far call and jump commands as well as the @Code and @Data symbols
  769. are not implemented.
  770.  
  771. The ret command:
  772.  
  773. The ret command without arguments is considered as a ret <parameter block
  774. size> command.  If you need to write the ret command without size you should
  775. set 0 explicitly:
  776.  
  777.       ret 0
  778.  
  779. Code-procedure
  780.  
  781. Besides the assembler-routine you can use the code-routine.  It has the
  782. following differences: the compiler doesn't emit the frame command on
  783. enter and return from the routine (including the ret command), and the local
  784. parameters are based on ESP on the moment of entry.
  785.  
  786. Example:
  787.  
  788.     function hi (n: word); code;
  789.     asm
  790.         mov al, byte ptr [n+1]
  791.         ret
  792.     end;
  793.  
  794.  
  795.            Supplied units:
  796.            ---------------
  797.  
  798. The following units are included:
  799.      SYSTEM.FPD - standard library functions
  800.         DOS.FPD - MS-DOS interface.
  801.                   Corresponds to the DOS unit of BP.
  802.         CRT.FPD - Text mode screen interface.
  803.                   Corresponds to the CRT unit of BP.
  804.       USE32.FPD - Define type Integer as 32-bit etc.
  805.    ERRCODES.FPD - Run-time error codes.
  806.       DEBUG.FPD - Some debugging code.
  807.     STRINGS.FPD - String handling functions.
  808.                   Corresponds to the STRINGS unit of BP.
  809.  
  810. Besides these modules, the distribution includes DOSCALL.FPD and ARG.FPD,
  811. which are needed for linkage. These modules should not be called by the user.
  812.  
  813.  
  814.            The DOS Unit
  815.            ------------
  816.  
  817. This corresponds to the DOS unit of BP.
  818.  
  819. Differences:
  820.  
  821.  Type FarPointer = record ofs: pointer; seg: word end;
  822.  
  823.  The function GetIntVec has the following syntax:
  824.      procedure GetIntVec (IntNo: Byte; var Vector: FarPointer);
  825.  
  826.  and not
  827.      procedure GetIntVec (IntNo: Byte; var Vector: Pointer);
  828.  
  829.  New procedures:
  830.  
  831.      procedure GetIntVecFar (IntNo: Byte;   var Vector: FarPointer);
  832.      procedure SetIntVecFar (IntNo: Byte; const Vector: FarPointer);
  833.  
  834.     GetIntVec is equivalent to GetIntVecFar().
  835.  
  836.     SetIntVec is equivalent to SetIntVecFar(), but uses in the segmented
  837.       address the current CS.
  838.  
  839. A header of an interrupt procedure should have the following form:
  840.  
  841. procedure handler (
  842.     eip, eax, ecx, edx, ebx, esp, ebp, esi, edi: dword;
  843.     gs, fs, es: word
  844. ); interrupt;
  845.  
  846.  
  847. The Registers type has this structure:
  848.  
  849.  type Registers =
  850.     record
  851.         edi, esi, ebp, _res : dword;
  852.     case boolean of
  853.         true:  (ebx, edx, ecx, eax: dword;
  854.                 flags, es, ds, fs, gs, ip, cs, sp, ss: word);
  855.         false: (bl, bh, b1, b2, dl, dh, d1, d2, cl, ch, c1, c2, al, ah: byte);
  856.     end;
  857.  
  858.  
  859.  
  860. !!! When using Intr() and MsDos(), keep in mind that the DOS
  861.     interrupt handlers can deal only with the addresses from the 1st
  862.     megabyte of memory.
  863.  
  864.  
  865.            The CRT unit
  866.            ------------
  867.  
  868. Corresponds to the CRT unit of BP.
  869.  
  870.            The USE32 unit
  871.            ------------
  872.  
  873. Contains redefinitions of integer types for 32-bit computing as follow:
  874.  
  875.     type
  876.       SmallInt   = System.Integer;
  877.       SmallWord  = System.Word;
  878.       Integer    = System.Longint;
  879.       Word       = System.Longint;
  880.  
  881.     const
  882.       MaxInt     = high(longint);
  883.  
  884.     type
  885.       PByte      = ^Byte;
  886.       PWord      = ^Word;
  887.       PLongint   = ^Longint;
  888.       PSmallInt  = ^SmallInt;
  889.       PSmallWord = ^SmallWord;
  890.  
  891.  
  892.            The ERRCODES unit
  893.            -----------------
  894.  
  895. Contains constants for error codes, given by RUNERROR(),
  896. and the error_msg(code: Word): String, function that decyphers the error code.
  897.  
  898.  
  899.            The DEBUG unit
  900.            --------------
  901.  
  902. This module prints out the error code and the call stack in case of a
  903. run-time error. The stack is printed as follows:
  904.  
  905. RunError #201 (range check error)
  906. Calls stack:
  907. SYSTEM.BOUND_ERROR [chk_fun.inp(21) at 0000000A]
  908. TEST.ASSN [TEST.PAS(61) at 00000015]
  909. TEST.TEST [TEST.PAS(82) at 0000001D]
  910.  
  911. To use DEBUG, simply list it in the USES clause of the main program.
  912.  
  913. +++0.33
  914.  
  915. Using the debug UNIT increases the .exe module size
  916.  
  917. !!! Note: a call of a procedure with a NULL address is currently diagnosed as
  918.     an arithmetic overflow, or (under the PMODE extender) caused a GP Fault or
  919.     other traps
  920. ---0.33
  921.  
  922.            The STRINGS unit
  923.            ----------------
  924.  
  925. Corresponds to the STRING unit of BP.
  926. Also contains additional functions:
  927.  
  928. Function hex (n: DWord   ): String [12];
  929.     -- prints the argument in hex.
  930.  
  931. Function whl (n: LongInt ): String [12];
  932.     -- prints the argument as a signed integer.
  933.  
  934. Function uns (n: DWord   ): String [12];
  935.     -- prints the argument as an unsigned integer.
  936.  
  937. Function fix (x: Extended; pr: LongInt): String [15];
  938.     -- prints a real with fixed point. pr is the number of digits after the
  939.        decimal point.
  940.  
  941. Function align (str: String; width: LongInt): String;
  942.     -- pads the argument up to width with spaces.
  943.        spaces are on the right if width>0, and on the left otherwise.
  944.  
  945. +++0.37
  946.  
  947.            The MOUSE unit
  948.            --------------
  949.  
  950. The MOUSE unit gives a Pascal program the access to the main
  951. mouse-support functions:
  952.         * Determining presense/absense of the mouse
  953.         * Mouse cursor positioning
  954.         * Getting information about the position and the button states
  955.         * Installing a mouse-driven Pascal interrupt handler.
  956.  
  957. Variables:
  958.  
  959. var ButtonCount:  Word;
  960.     During initilaization has value 0; after a call to InitMouse()
  961.     this variable becomes either 0 (no mouse), or the number of
  962.     available buttons (2 or 3).
  963.  
  964. Procedures & Functions:
  965.  
  966. Procedure InitMouse;
  967.  
  968.      Does the following:
  969.      - Allocates a 4K stack for the user's mouse interrupt-driven
  970.        procedure.
  971.      - Determines the presence or absence of the mouse and sets the
  972.        ButtonCount variable.
  973.      - If mouse is present:
  974.           - Enables the mouse cursor (calls ShowMouse)
  975.           - Positions the cursor to the upper-left screen corner;
  976.           - Reserves the callback address for the users' interrupt-driven
  977.             mouse procedure (regardless of whether it will get installed or
  978.             not).
  979.  
  980. Procedure ShowMouse;
  981.  
  982.      When mouse is present, makes its cursor visible (INT 33 01).
  983.  
  984. Procedure HideMouse;
  985.  
  986.      When mouse is present, makes its cursor invisible (INT 33 02).
  987.  
  988. Procedure SetMousePos (X, Y: Integer);
  989.  
  990.      Positions the Mouse Cursor to the point (X,Y).
  991.      Both coordinates start with 0.
  992.  
  993. Procedure GetMouseInfo (var ButtonMask:Word;  var X:Word; var Y:Word);
  994.  
  995.      Returns information about the position of the mouse cursor (X,Y)
  996.      and the pressed buttons (ButtonMask).
  997.  
  998. Procedure SetMouseHandler (Mask:Word;
  999.                                 procedure Hnd (Mask,
  1000.                                                Buttons,
  1001.                                                X,Y,
  1002.                                                MovX,MovY:Word;))
  1003.  
  1004.      Installs a Pascal interrupt-driven user's mouse handler (Hnd).
  1005.      The Mask parameter defines the classes of the events that call
  1006.      the handler; its format corresponds to the function INT 33 0C.
  1007.      When Hnd is called the Mask parameter contains the mask with the
  1008.      event type that occurred; Buttons contain the mask of the currently
  1009.      pressed buttons; X and Y contain the cursor's absolute position, and
  1010.      MovX and MovY contain the relative (signed) change of the last cursor
  1011.      position [negative numbers mean left or down; positive mean
  1012.      right or up]. These values are given in mouse position units; to
  1013.      convert to symbols, they need to be divided by 8.
  1014.  
  1015.      Using SetMouseHandler you can install several handlers with different
  1016.      masks without having to clear previous handlers.
  1017.  
  1018. Procedure ClearMouseHandler;
  1019.  
  1020.      Removes the user's mouse interrupt handler.
  1021.  
  1022. Procedure DoneMouse;
  1023.  
  1024.      Does the following:
  1025.  
  1026.         - removes (hides) the mouse cursor;
  1027.         - frees the callback address for the mouse interrupt handler;
  1028.         - frees the stack for the mouse interrupt handlers;
  1029.         - resets ButtonCount to 0.
  1030. ---0.37
  1031.  
  1032. +++0.33
  1033. *******************VERSION 0.33 CHANGES*******************************
  1034.  
  1035. This version of the compiler uses a new DOS extender (based on the
  1036. PMODE package). It emulates the DOS32 functions that are necessary
  1037. for run-time support of Pascal programs, which allows to use both the
  1038. new extender as well as DOS32. The full list of the DOS32 functions, which are
  1039. supported by the new extender is given at the end of this document
  1040. The main difference of the new extender is that the 1st MB of the physical
  1041. RAM is mapped to the 1st MB of the virtual memory while the program is
  1042. loaded into higher addressed. This corresponds to the value _zero = 0.
  1043. Thus, with the new extender it is possible to use absolute memory addressing:
  1044.  
  1045.    var vmem: array [1..25, 1..80] of word absolute $b8000;
  1046.  
  1047. Because of this we could now implement some other BP7.0 constructs:
  1048.  
  1049.     mem [seg:offs]
  1050.     var x:type absolute seg:offs
  1051.  
  1052. Here the effective address is computed as seg*16+offs.
  1053. The Ptr (seg, offs) function works similarly. The seg(v)
  1054. function still always returns 0.
  1055.  
  1056. These new functions should substantially simplify the conversion of the
  1057. programs that use absolute addressing.
  1058.  
  1059. An example of using these functions can be found in file
  1060. EXAMPLES\FLAME\FLAME1.PAS
  1061.  
  1062. By default PLT uses the new extender (stub passtub.exe);
  1063. the old one (DOS32) can be used by specifying the
  1064. command line parameter -stub:dos32.exe or adding the line
  1065.         stub dos32.exe
  1066. in the configuration file.
  1067.  
  1068. The support for the DOS32 extender is likely to be entirely removed
  1069. in the next version of PLT. Unless you discover some specific problems
  1070. with the new extender (please report them if you do!), you should not
  1071. use the DOS32 stub loader.
  1072.  
  1073. ---------
  1074.  
  1075. The following DOS32 functions are supported by the new extender:
  1076.  
  1077. subfunctions of INT 31h:
  1078.    EE40h
  1079.    EE42h
  1080.  
  1081. subfunctions of INT 21h:
  1082.   39h, 3Ah, 3Bh, 3Ch, 3Dh, 3Fh, 40h
  1083.   41h, 42h, 4300h, 4301h, 47h, 4Bh, 4Eh, 4Fh, 56h, 5Ah, 5Bh
  1084.  
  1085. **********************************************************************
  1086. ---0.33
  1087.  
  1088. +++0.37
  1089. *******************VERSION 0.37 CHANGES*******************************
  1090. New unit: MOUSE.
  1091.  
  1092. No syntax changes; numerous errors in the PMODE-based extender and
  1093. the compiler are corrected.
  1094. **********************************************************************
  1095. ---0.37
  1096.  
  1097.                    Possible problems during usage
  1098.                    ------------------------------
  1099.  
  1100.     Programs, generated by TMT Pascal, abend under OS/2. Correction:
  1101.       - ensure that in "memory settings" EMS_MEMORY_LIMIT is not equal to 0.
  1102.  
  1103. +++0.33
  1104.                    Run-time errors codes
  1105.                    -------- ------ -----
  1106.  
  1107.   1    Invalid function number
  1108.   2    File not found
  1109.   3    Path not found
  1110.   4    Too many open files
  1111.   5    File access denied
  1112.   6    Invalid file handle
  1113.  12    Invalid file access_code
  1114.  15    Invalid drive number
  1115.  16    Cannot remove current directory
  1116.  17    Cannot rename across drives
  1117.  18    No more files
  1118. 100    Disk read error
  1119. 101    Disk write error
  1120. 102    File not assigned
  1121. 103    File not open
  1122. 104    File not open for input
  1123. 105    File not open for output
  1124. 106    Invalid numeric format
  1125. 150    Disk is write protected
  1126. 151    Bad drive request struct length
  1127. 152    Drive not ready
  1128. 154    CRC error in data
  1129. 156    Disk seek error
  1130. 157    Unknown media type
  1131. 158    Sector not found
  1132. 159    Printer out of paper
  1133. 160    Device write fault
  1134. 161    Device read fault
  1135. 162    Hardware failure
  1136. 200    Division by zero
  1137. 201    Range check error
  1138. 202    Stack overflow error
  1139. 203    Heap overflow error
  1140. 204    Invalid pointer operation
  1141. 205    Floating point overflow
  1142. 206    Floating point underflow
  1143. 207    Invalid floating point operation
  1144. 208    Overlay manager not installed
  1145. 209    Overlay file read error
  1146. 210    Object not initialized
  1147. 211    Call to abstract method
  1148. 212    Stream registration error
  1149. 213    Collection index_out of range
  1150. 214    Collection overflow error
  1151. 215    Arithmetic overflow error
  1152. 216    General protection fault
  1153. 217    Invalid operation_code
  1154. 300    File io error
  1155. 301    Nonmatched array bounds
  1156. 302    Non local procedure pointer
  1157. 303    Procedure pointer out of scope
  1158. 304    Function not implemented
  1159. 305    Breakpoint error
  1160. 306    Break by ctrl/C
  1161. 307    Break by ctrl break
  1162. 308    Break by other process
  1163. 309    No floating point coprocessor
  1164.  
  1165. ---0.33
  1166.